.TH "display-file" 7 "2007-04-17" "libggi-current" GGI
.SH NAME
\fBdisplay-file\fR : Render display into image file
.SH SYNOPSIS
.nb
.nf
display-file: [-flushcmd=<command>] [-flushframe=<n>]
              [-flushtime=<t>] [-ppm] [-yuv] <filename>
.fi

.SH DESCRIPTION
Renders an image into a file.  The file can be a framebuffer device
(e.g. \fB/dev/fb0\fR), in which case a reasonable representation of the
image will be drawn on the console \fIso long as\fR the program's mode
matches the framebuffer's mode.
.RS
\fBNote:\fR
This target generates no input.  The \fBdisplay-multi(7)\fR target can be
used in order to see (and control) what the program does (using a
normal target) and then generate a snapshot when the program
exits.
.RE
.SH OPTIONS
\fIfilename\fR is the file to render the images to.  If a non-default
file type (ppm or yuv) is specified in other options, then the image will 
be generated at \fBggiClose(3)\fR time (unless \f(CW-flushtime\fR or \f(CW-flushframe\fR
are specified).  Otherwise the file is a custom \fIGGIFILE\fR format and is 
generated continuously.

\fI-ppm\fR write the file as PPM pixmap. PPM can be easily converted to
other formats using pbmtools, cjpeg and other converters.

\fI-yuv\fR write a movie file as YUV stream suitable for processing with
e.g. mpeg2enc or ffmpeg. A frame will be written at the times specified 
in \f(CW-flushtime\fR or \f(CW-flushframe\fR.

The \fBdisplay-file\fR target can be used to generate movies from running
LibGGI applications. To do this, either use the yuv format, or set 
\f(CW-flushcmd\fR to a shell command to execute at the times given 
by one of the two other parameters. This looks typically like:

.nb
.nf
ppmtogif foo.ppm > foo.%04d.gif
.fi

The command is passed through a \f(CWprintf(3)\fR which has the current
count of saved frames as an argument (or rather as 10 arguments to
allow a few more complex commands).

The primary file is updated at every \fIn\fR-th invocation of ggiFlush 
or every \fIt\fR seconds, where \fIt\fR can have fractional components 
(specified as decimal) before the shell command (if given) is run.

Note, that the invocation of the shell command will slow down the
program, so make sure you use a reasonable value, if you use the
\f(CW-flushtime\fR argument.
.SH FEATURES
.IP \(bu 4
DirectBuffer always available.
.IP \(bu 4
Unaccelerated.
.PP
